\documentclass[a4paper,11pt]{report}
\usepackage{multicol}
\usepackage[english]{babel}

% Title Page
\title{\begin{Large}\textbf{Building a compiler for a custom MIPS-like instruction set}\end{Large}}
\author{Vittorio Giovara\\Fabio Margaglia\\Francesco Meo\\Lorenzo Simone}
\date{\vspace{3cm}
\begin{footnotesize}\textit{document revision 1.2}\end{footnotesize}}


\begin{document}
\maketitle
\tableofcontents
\chapter{Introduction}
The aim of this report is to provide documentation about the use of the instruction set of a custom MIPS-like processor and about the internal code of the compiler.

This document will list the implemented instructions and their assembly-like structure. Afterwards it will present the use of the compiler itself as well as the explanation of the involved code about the scanner and parsing technique.

The compiler comes with an emulator, that preforms simulated execution of the compiled code.


\chapter{Instruction List}
\begin{multicols}{2}
\begin{itemize}
 \item NOP
 \item ADDU
 \item ADDS
 \item SUBU
 \item SUBS
 \item MULU
 \item MULS
 \item DIVU
 \item DIVS
 \item AND
 \item OR
 \item XOR
 \item LD32
 \item LD16
 \item LD8
 \item ST32
 \item ST16
 \item ST8
 \item JMP
 \item JAL
 \item JZ
 \item JNZ
 \item JLZ
 \item JGZ
 \item JLEZ
 \item JGEZ
 \item LLS
 \item LRS
 \item ALS
 \item ARS
 \item LR
 \item RR
 \item MOV
\end{itemize}
\end{multicols}


\section{Instruction Rules}

\subsection{Arithmetical Operations}
\begin{description}
 \item[parameter 1]: Destination Register ($R_d$\footnote{in register to register operations} or $R_t$\footnote{in register to immediate operations})
 \item[parameter 2]: Source Register ($R_s$)
 \item[parameter 3]: Source Register ($R_t$) or Immediate
\end{description}
\subsection{Logical Operations}
\begin{description}
 \item[parameter 1]: Destination Register ($R_d$ or $R_t$)
 \item[parameter 2]: Source Register ($R_s$)
 \item[parameter 3]: Source Register ($R_t$) or Immediate
\end{description}
\subsection{Memory Operations}
\subsubsection{LOAD}
\begin{description}
 \item[parameter 1]: Destination Register ($R_t$)
 \item[parameter 2]: Source Register ($R_s$)
 \item[parameter 3]: Immediate
\end{description}
\subsubsection{STORE}
\begin{description}
 \item[parameter 1]: Source Register ($R_t$)
 \item[parameter 2]: Destination Register ($R_s$)
 \item[parameter 3]: Immediate
\end{description}
\section{Jump Operations}
\begin{description}
 \item[parameter]: Immediate or Register
\end{description}
\subsection{Branch Operations}
\begin{description}
 \item[parameter 1]: Register ($R_s$)
 \item[parameter 2]: Immediate or Register ($R_t$)
\end{description}
\subsection{Shift Operations}
\begin{description}
 \item[parameter 1]: Destination Register ($R_d$)
 \item[parameter 2]: Source Register ($R_s$)
 \item[parameter 3]: Register ($R_t$) \footnote{\textit{Defines the shift or rotate amount}}
\end{description}
\subsection{Special Operations}
\subsubsection{MOV}
\begin{description}
 \item[parameter 1]: Destination Register ($R_t$ or $R_d$)
 \item[parameter 2]: Immediate or Register ($R_t$)
\end{description}
\subsubsection{NOP}
No arguments needed.

\chapter{Compiler structure}
The compiler needs 3 arguments to be passed by command line:

\begin{description}
 \item[Input file:] The source file for the assembly-like code;
 \item[Verbosity level:] Selects the quantity of ouput message printed;
 \item[Emulation level:] Turns on or off the emulation.
 %\item[Output file:] The output file in text format (containg binary values).
\end{description}

The \textit{verbosity level} is a number between 0 (meaning no output at all) and 4 (meaning that every single step of the scanner and of the parser are notified); error messages are always printed. When none is specified, a default is set to 1.

The \textit{emulation level} is a flag that manages the emulation execution, 0 deactivates this feature, 1 activates it and 2 gives information about the program counter. When none is specified, a default is set to 0.

The output file on which the binary encoding is saved is always named  \texttt{code.bin}.

\section{The JFlex scanner}
The scanner initially defines two additional contexes for handling the comments: one for single line comments (active from \texttt{//} to a new line), and the other for multi line comments (enclosed in \texttt{/*} and \texttt{*/}).

Then it describes the syntactic rules, using the following macros:

\begin{description}
 \item[nl] The new line symbol for different operating systems;
 \item[ignored] List of charaters or symbols that can be safely ignored;
 \item[register] The structure for registers (capital R followed by a number between 0 and 31);
 \item[integer] Structure for integers (optional sign followed by a natural number);
 \item[separator] The character that separates the instruction arguments; 
 \item[eol] The character that concludes the instruction.
\end{description}

The actual operations are not defined by macros but are aggregated: for example mathematicatical operations that can be signed or unsigned are described by the same rule (eg. the addition is described as \texttt{ADD(U|S) not as \texttt{ADDU} and \texttt{ADDS}} but inside that rule the two possible symbols are differenciated.

Every rule passes a symbol to CUP, with some attributes: the number for the register and the kind of operation for the base instructions.

\section{The CUP parser}
The parser defines a terminal symbol for each possible operation, and the set of arguments (INT, COMA, REG, EOL); then it describes the productions in the following way:

\begin{itemize}
\item op $\longrightarrow$ \textit{any possible operation}\\
\textit{translates from terminal symbol to non-terminal saving the string attribute};
\item register $\longrightarrow$ REG\\
\textit{passes the attribute to top level};
\item arguments 
	\begin{itemize}
	\item[$\longrightarrow$] register COMA register COMA INT EOL\\
	 \textit{for register-to-immediate instructions}
	\item[$\longrightarrow$] register COMA register COMA register EOL\\
	 \textit{for register-to-register instructions};
	\item[$\longrightarrow$] register COMA INT EOL \textit{or} register COMA register EOL\\
	 \textit{for conditional branch instructions};
	\item[$\longrightarrow$]  register EOL \textit{or} INT EOL\\
	 \textit{for unconditional branch instructions};
	\item[$\longrightarrow$] EOL\\
	 \textit{for the no-operation instruction}.
	\end{itemize}
\item line $\longrightarrow$ op arguments\\
\textit{joins the operation with its arguments};
\item instruction $\longrightarrow$ line\\
\textit{renames the non terminal symbol and discards the attributes};
\item list $\longrightarrow$ instruction \textit{or} list instruction\\
\textit{allows to parse more than one instruction};
\item program $\longrightarrow$ list\\
\textit{renames the non terminal symbol and produces the starting symbol}.
\end{itemize}

\subsection{Instruction Encoding and Emulation}
When \texttt{line} gets produced (operation and arguments are available) the instruction is both encoded and emulated.  According to the type of arguments in the production \texttt{arguments} a status variable (\texttt{flag}) is set up and it changes the output encoding and emulation result.

In order to perform the encoding, a file named \texttt{rules\_encoding} is loaded in the program and generates an hash map in which each instruction is associated with its binary code; the string used to determine the type of operation is used as a key to the hash map. When an instruction is encoded the integer values are converted in binary string with the function \texttt{printBin()} and placed in the output string.

As for the emulation, the registers and the cache memory are emulated using two integer vectors of size 32 and 256\footnote{\textit{this is due to the actual processor that has such dimesion because of synthesis \-constraints.}} respectively and both are initialized with \texttt{initRegandMem()}. Then using the same structure of the encoding section it proceeds to perfom a the detected operation by getting the integer values of the register (used as vector index) and immediate numbers and to print on screen the output result.

The emulation is capable of handlint unsigned integer numbers (whose native type is absent in Java) through the use of \texttt{unsignedOperation()} function.

\subsection{Error Handling}
The main focus of error handling is to force the parser to continue reading from the file instead of aborting execution; so after an error the parser must not stop.

In order to achieve this behaviour, special terminal symbol \texttt{error} is used and inserted in productions that can cause an unexpected behaviour. As a matter of fact the \texttt{error} symbol is present in the \texttt{arguments} production for correctly handling wrong argument formats like inserting more than three arguments.

However error correction is also obtained using once again the \texttt{flag} structure: since a different argument format gives a different value to this variable, it is possible to recognise a wrong argument format just by checking its value: for example in mathematical operations that can handle only two registers and an immediate (flag is 0) or three registers (flag is 1), only those two values are accepted while all the other configurations are rejected.

\end{document}
